home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / FLAC / metadata.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-10  |  97.0 KB  |  2,182 lines
  1. /* libFLAC - Free Lossless Audio Codec library
  2.  * Copyright (C) 2001,2002,2003,2004,2005,2006,2007  Josh Coalson
  3.  *
  4.  * Redistribution and use in source and binary forms, with or without
  5.  * modification, are permitted provided that the following conditions
  6.  * are met:
  7.  *
  8.  * - Redistributions of source code must retain the above copyright
  9.  * notice, this list of conditions and the following disclaimer.
  10.  *
  11.  * - Redistributions in binary form must reproduce the above copyright
  12.  * notice, this list of conditions and the following disclaimer in the
  13.  * documentation and/or other materials provided with the distribution.
  14.  *
  15.  * - Neither the name of the Xiph.org Foundation nor the names of its
  16.  * contributors may be used to endorse or promote products derived from
  17.  * this software without specific prior written permission.
  18.  *
  19.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20.  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22.  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
  23.  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  24.  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  25.  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  26.  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  27.  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  28.  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  29.  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30.  */
  31.  
  32. #ifndef FLAC__METADATA_H
  33. #define FLAC__METADATA_H
  34.  
  35. #include <sys/types.h> /* for off_t */
  36. #include "export.h"
  37. #include "callback.h"
  38. #include "format.h"
  39.  
  40. /* --------------------------------------------------------------------
  41.    (For an example of how all these routines are used, see the source
  42.    code for the unit tests in src/test_libFLAC/metadata_*.c, or
  43.    metaflac in src/metaflac/)
  44.    ------------------------------------------------------------------*/
  45.  
  46. /** \file include/FLAC/metadata.h
  47.  *
  48.  *  \brief
  49.  *  This module provides functions for creating and manipulating FLAC
  50.  *  metadata blocks in memory, and three progressively more powerful
  51.  *  interfaces for traversing and editing metadata in FLAC files.
  52.  *
  53.  *  See the detailed documentation for each interface in the
  54.  *  \link flac_metadata metadata \endlink module.
  55.  */
  56.  
  57. /** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces
  58.  *  \ingroup flac
  59.  *
  60.  *  \brief
  61.  *  This module provides functions for creating and manipulating FLAC
  62.  *  metadata blocks in memory, and three progressively more powerful
  63.  *  interfaces for traversing and editing metadata in native FLAC files.
  64.  *  Note that currently only the Chain interface (level 2) supports Ogg
  65.  *  FLAC files, and it is read-only i.e. no writing back changed
  66.  *  metadata to file.
  67.  *
  68.  *  There are three metadata interfaces of increasing complexity:
  69.  *
  70.  *  Level 0:
  71.  *  Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and
  72.  *  PICTURE blocks.
  73.  *
  74.  *  Level 1:
  75.  *  Read-write access to all metadata blocks.  This level is write-
  76.  *  efficient in most cases (more on this below), and uses less memory
  77.  *  than level 2.
  78.  *
  79.  *  Level 2:
  80.  *  Read-write access to all metadata blocks.  This level is write-
  81.  *  efficient in all cases, but uses more memory since all metadata for
  82.  *  the whole file is read into memory and manipulated before writing
  83.  *  out again.
  84.  *
  85.  *  What do we mean by efficient?  Since FLAC metadata appears at the
  86.  *  beginning of the file, when writing metadata back to a FLAC file
  87.  *  it is possible to grow or shrink the metadata such that the entire
  88.  *  file must be rewritten.  However, if the size remains the same during
  89.  *  changes or PADDING blocks are utilized, only the metadata needs to be
  90.  *  overwritten, which is much faster.
  91.  *
  92.  *  Efficient means the whole file is rewritten at most one time, and only
  93.  *  when necessary.  Level 1 is not efficient only in the case that you
  94.  *  cause more than one metadata block to grow or shrink beyond what can
  95.  *  be accomodated by padding.  In this case you should probably use level
  96.  *  2, which allows you to edit all the metadata for a file in memory and
  97.  *  write it out all at once.
  98.  *
  99.  *  All levels know how to skip over and not disturb an ID3v2 tag at the
  100.  *  front of the file.
  101.  *
  102.  *  All levels access files via their filenames.  In addition, level 2
  103.  *  has additional alternative read and write functions that take an I/O
  104.  *  handle and callbacks, for situations where access by filename is not
  105.  *  possible.
  106.  *
  107.  *  In addition to the three interfaces, this module defines functions for
  108.  *  creating and manipulating various metadata objects in memory.  As we see
  109.  *  from the Format module, FLAC metadata blocks in memory are very primitive
  110.  *  structures for storing information in an efficient way.  Reading
  111.  *  information from the structures is easy but creating or modifying them
  112.  *  directly is more complex.  The metadata object routines here facilitate
  113.  *  this by taking care of the consistency and memory management drudgery.
  114.  *
  115.  *  Unless you will be using the level 1 or 2 interfaces to modify existing
  116.  *  metadata however, you will not probably not need these.
  117.  *
  118.  *  From a dependency standpoint, none of the encoders or decoders require
  119.  *  the metadata module.  This is so that embedded users can strip out the
  120.  *  metadata module from libFLAC to reduce the size and complexity.
  121.  */
  122.  
  123. #ifdef __cplusplus
  124. extern "C" {
  125. #endif
  126.  
  127.  
  128. /** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface
  129.  *  \ingroup flac_metadata
  130.  *
  131.  *  \brief
  132.  *  The level 0 interface consists of individual routines to read the
  133.  *  STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring
  134.  *  only a filename.
  135.  *
  136.  *  They try to skip any ID3v2 tag at the head of the file.
  137.  *
  138.  * \{
  139.  */
  140.  
  141. /** Read the STREAMINFO metadata block of the given FLAC file.  This function
  142.  *  will try to skip any ID3v2 tag at the head of the file.
  143.  *
  144.  * \param filename    The path to the FLAC file to read.
  145.  * \param streaminfo  A pointer to space for the STREAMINFO block.  Since
  146.  *                    FLAC__StreamMetadata is a simple structure with no
  147.  *                    memory allocation involved, you pass the address of
  148.  *                    an existing structure.  It need not be initialized.
  149.  * \assert
  150.  *    \code filename != NULL \endcode
  151.  *    \code streaminfo != NULL \endcode
  152.  * \retval FLAC__bool
  153.  *    \c true if a valid STREAMINFO block was read from \a filename.  Returns
  154.  *    \c false if there was a memory allocation error, a file decoder error,
  155.  *    or the file contained no STREAMINFO block.  (A memory allocation error
  156.  *    is possible because this function must set up a file decoder.)
  157.  */
  158. FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);
  159.  
  160. /** Read the VORBIS_COMMENT metadata block of the given FLAC file.  This
  161.  *  function will try to skip any ID3v2 tag at the head of the file.
  162.  *
  163.  * \param filename    The path to the FLAC file to read.
  164.  * \param tags        The address where the returned pointer will be
  165.  *                    stored.  The \a tags object must be deleted by
  166.  *                    the caller using FLAC__metadata_object_delete().
  167.  * \assert
  168.  *    \code filename != NULL \endcode
  169.  *    \code tags != NULL \endcode
  170.  * \retval FLAC__bool
  171.  *    \c true if a valid VORBIS_COMMENT block was read from \a filename,
  172.  *    and \a *tags will be set to the address of the metadata structure.
  173.  *    Returns \c false if there was a memory allocation error, a file
  174.  *    decoder error, or the file contained no VORBIS_COMMENT block, and
  175.  *    \a *tags will be set to \c NULL.
  176.  */
  177. FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags);
  178.  
  179. /** Read the CUESHEET metadata block of the given FLAC file.  This
  180.  *  function will try to skip any ID3v2 tag at the head of the file.
  181.  *
  182.  * \param filename    The path to the FLAC file to read.
  183.  * \param cuesheet    The address where the returned pointer will be
  184.  *                    stored.  The \a cuesheet object must be deleted by
  185.  *                    the caller using FLAC__metadata_object_delete().
  186.  * \assert
  187.  *    \code filename != NULL \endcode
  188.  *    \code cuesheet != NULL \endcode
  189.  * \retval FLAC__bool
  190.  *    \c true if a valid CUESHEET block was read from \a filename,
  191.  *    and \a *cuesheet will be set to the address of the metadata
  192.  *    structure.  Returns \c false if there was a memory allocation
  193.  *    error, a file decoder error, or the file contained no CUESHEET
  194.  *    block, and \a *cuesheet will be set to \c NULL.
  195.  */
  196. FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet);
  197.  
  198. /** Read a PICTURE metadata block of the given FLAC file.  This
  199.  *  function will try to skip any ID3v2 tag at the head of the file.
  200.  *  Since there can be more than one PICTURE block in a file, this
  201.  *  function takes a number of parameters that act as constraints to
  202.  *  the search.  The PICTURE block with the largest area matching all
  203.  *  the constraints will be returned, or \a *picture will be set to
  204.  *  \c NULL if there was no such block.
  205.  *
  206.  * \param filename    The path to the FLAC file to read.
  207.  * \param picture     The address where the returned pointer will be
  208.  *                    stored.  The \a picture object must be deleted by
  209.  *                    the caller using FLAC__metadata_object_delete().
  210.  * \param type        The desired picture type.  Use \c -1 to mean
  211.  *                    "any type".
  212.  * \param mime_type   The desired MIME type, e.g. "image/jpeg".  The
  213.  *                    string will be matched exactly.  Use \c NULL to
  214.  *                    mean "any MIME type".
  215.  * \param description The desired description.  The string will be
  216.  *                    matched exactly.  Use \c NULL to mean "any
  217.  *                    description".
  218.  * \param max_width   The maximum width in pixels desired.  Use
  219.  *                    \c (unsigned)(-1) to mean "any width".
  220.  * \param max_height  The maximum height in pixels desired.  Use
  221.  *                    \c (unsigned)(-1) to mean "any height".
  222.  * \param max_depth   The maximum color depth in bits-per-pixel desired.
  223.  *                    Use \c (unsigned)(-1) to mean "any depth".
  224.  * \param max_colors  The maximum number of colors desired.  Use
  225.  *                    \c (unsigned)(-1) to mean "any number of colors".
  226.  * \assert
  227.  *    \code filename != NULL \endcode
  228.  *    \code picture != NULL \endcode
  229.  * \retval FLAC__bool
  230.  *    \c true if a valid PICTURE block was read from \a filename,
  231.  *    and \a *picture will be set to the address of the metadata
  232.  *    structure.  Returns \c false if there was a memory allocation
  233.  *    error, a file decoder error, or the file contained no PICTURE
  234.  *    block, and \a *picture will be set to \c NULL.
  235.  */
  236. FLAC_API FLAC__bool FLAC__metadata_get_picture(const char *filename, FLAC__StreamMetadata **picture, FLAC__StreamMetadata_Picture_Type type, const char *mime_type, const FLAC__byte *description, unsigned max_width, unsigned max_height, unsigned max_depth, unsigned max_colors);
  237.  
  238. /* \} */
  239.  
  240.  
  241. /** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface
  242.  *  \ingroup flac_metadata
  243.  *
  244.  * \brief
  245.  * The level 1 interface provides read-write access to FLAC file metadata and
  246.  * operates directly on the FLAC file.
  247.  *
  248.  * The general usage of this interface is:
  249.  *
  250.  * - Create an iterator using FLAC__metadata_simple_iterator_new()
  251.  * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check
  252.  *   the exit code.  Call FLAC__metadata_simple_iterator_is_writable() to
  253.  *   see if the file is writable, or only read access is allowed.
  254.  * - Use FLAC__metadata_simple_iterator_next() and
  255.  *   FLAC__metadata_simple_iterator_prev() to traverse the blocks.
  256.  *   This is does not read the actual blocks themselves.
  257.  *   FLAC__metadata_simple_iterator_next() is relatively fast.
  258.  *   FLAC__metadata_simple_iterator_prev() is slower since it needs to search
  259.  *   forward from the front of the file.
  260.  * - Use FLAC__metadata_simple_iterator_get_block_type() or
  261.  *   FLAC__metadata_simple_iterator_get_block() to access the actual data at
  262.  *   the current iterator position.  The returned object is yours to modify
  263.  *   and free.
  264.  * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block
  265.  *   back.  You must have write permission to the original file.  Make sure to
  266.  *   read the whole comment to FLAC__metadata_simple_iterator_set_block()
  267.  *   below.
  268.  * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks.
  269.  *   Use the object creation functions from
  270.  *   \link flac_metadata_object here \endlink to generate new objects.
  271.  * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block
  272.  *   currently referred to by the iterator, or replace it with padding.
  273.  * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when
  274.  *   finished.
  275.  *
  276.  * \note
  277.  * The FLAC file remains open the whole time between
  278.  * FLAC__metadata_simple_iterator_init() and
  279.  * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering
  280.  * the file during this time.
  281.  *
  282.  * \note
  283.  * Do not modify the \a is_last, \a length, or \a type fields of returned
  284.  * FLAC__StreamMetadata objects.  These are managed automatically.
  285.  *
  286.  * \note
  287.  * If any of the modification functions
  288.  * (FLAC__metadata_simple_iterator_set_block(),
  289.  * FLAC__metadata_simple_iterator_delete_block(),
  290.  * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false,
  291.  * you should delete the iterator as it may no longer be valid.
  292.  *
  293.  * \{
  294.  */
  295.  
  296. struct FLAC__Metadata_SimpleIterator;
  297. /** The opaque structure definition for the level 1 iterator type.
  298.  *  See the
  299.  *  \link flac_metadata_level1 metadata level 1 module \endlink
  300.  *  for a detailed description.
  301.  */
  302. typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator;
  303.  
  304. /** Status type for FLAC__Metadata_SimpleIterator.
  305.  *
  306.  *  The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status().
  307.  */
  308. typedef enum {
  309.  
  310.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0,
  311.     /**< The iterator is in the normal OK state */
  312.  
  313.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,
  314.     /**< The data passed into a function violated the function's usage criteria */
  315.  
  316.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,
  317.     /**< The iterator could not open the target file */
  318.  
  319.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE,
  320.     /**< The iterator could not find the FLAC signature at the start of the file */
  321.  
  322.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE,
  323.     /**< The iterator tried to write to a file that was not writable */
  324.  
  325.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA,
  326.     /**< The iterator encountered input that does not conform to the FLAC metadata specification */
  327.  
  328.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR,
  329.     /**< The iterator encountered an error while reading the FLAC file */
  330.  
  331.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR,
  332.     /**< The iterator encountered an error while seeking in the FLAC file */
  333.  
  334.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR,
  335.     /**< The iterator encountered an error while writing the FLAC file */
  336.  
  337.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR,
  338.     /**< The iterator encountered an error renaming the FLAC file */
  339.  
  340.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR,
  341.     /**< The iterator encountered an error removing the temporary file */
  342.  
  343.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR,
  344.     /**< Memory allocation failed */
  345.  
  346.     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR
  347.     /**< The caller violated an assertion or an unexpected error occurred */
  348.  
  349. } FLAC__Metadata_SimpleIteratorStatus;
  350.  
  351. /** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string.
  352.  *
  353.  *  Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array
  354.  *  will give the string equivalent.  The contents should not be modified.
  355.  */
  356. extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[];
  357.  
  358.  
  359. /** Create a new iterator instance.
  360.  *
  361.  * \retval FLAC__Metadata_SimpleIterator*
  362.  *    \c NULL if there was an error allocating memory, else the new instance.
  363.  */
  364. FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void);
  365.  
  366. /** Free an iterator instance.  Deletes the object pointed to by \a iterator.
  367.  *
  368.  * \param iterator  A pointer to an existing iterator.
  369.  * \assert
  370.  *    \code iterator != NULL \endcode
  371.  */
  372. FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator);
  373.  
  374. /** Get the current status of the iterator.  Call this after a function
  375.  *  returns \c false to get the reason for the error.  Also resets the status
  376.  *  to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK.
  377.  *
  378.  * \param iterator  A pointer to an existing iterator.
  379.  * \assert
  380.  *    \code iterator != NULL \endcode
  381.  * \retval FLAC__Metadata_SimpleIteratorStatus
  382.  *    The current status of the iterator.
  383.  */
  384. FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator);
  385.  
  386. /** Initialize the iterator to point to the first metadata block in the
  387.  *  given FLAC file.
  388.  *
  389.  * \param iterator             A pointer to an existing iterator.
  390.  * \param filename             The path to the FLAC file.
  391.  * \param read_only            If \c true, the FLAC file will be opened
  392.  *                             in read-only mode; if \c false, the FLAC
  393.  *                             file will be opened for edit even if no
  394.  *                             edits are performed.
  395.  * \param preserve_file_stats  If \c true, the owner and modification
  396.  *                             time will be preserved even if the FLAC
  397.  *                             file is written to.
  398.  * \assert
  399.  *    \code iterator != NULL \endcode
  400.  *    \code filename != NULL \endcode
  401.  * \retval FLAC__bool
  402.  *    \c false if a memory allocation error occurs, the file can't be
  403.  *    opened, or another error occurs, else \c true.
  404.  */
  405. FLAC_API FLAC__bool FLAC__metadata_simple_iterator_init(FLAC__Metadata_SimpleIterator *iterator, const char *filename, FLAC__bool read_only, FLAC__bool preserve_file_stats);
  406.  
  407. /** Returns \c true if the FLAC file is writable.  If \c false, calls to
  408.  *  FLAC__metadata_simple_iterator_set_block() and
  409.  *  FLAC__metadata_simple_iterator_insert_block_after() will fail.
  410.  *
  411.  * \param iterator             A pointer to an existing iterator.
  412.  * \assert
  413.  *    \code iterator != NULL \endcode
  414.  * \retval FLAC__bool
  415.  *    See above.
  416.  */
  417. FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);
  418.  
  419. /** Moves the iterator forward one metadata block, returning \c false if
  420.  *  already at the end.
  421.  *
  422.  * \param iterator  A pointer to an existing initialized iterator.
  423.  * \assert
  424.  *    \code iterator != NULL \endcode
  425.  *    \a iterator has been successfully initialized with
  426.  *    FLAC__metadata_simple_iterator_init()
  427.  * \retval FLAC__bool
  428.  *    \c false if already at the last metadata block of the chain, else
  429.  *    \c true.
  430.  */
  431. FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator);
  432.  
  433. /** Moves the iterator backward one metadata block, returning \c false if
  434.  *  already at the beginning.
  435.  *
  436.  * \param iterator  A pointer to an existing initialized iterator.
  437.  * \assert
  438.  *    \code iterator != NULL \endcode
  439.  *    \a iterator has been successfully initialized with
  440.  *    FLAC__metadata_simple_iterator_init()
  441.  * \retval FLAC__bool
  442.  *    \c false if already at the first metadata block of the chain, else
  443.  *    \c true.
  444.  */
  445. FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator);
  446.  
  447. /** Returns a flag telling if the current metadata block is the last.
  448.  *
  449.  * \param iterator  A pointer to an existing initialized iterator.
  450.  * \assert
  451.  *    \code iterator != NULL \endcode
  452.  *    \a iterator has been successfully initialized with
  453.  *    FLAC__metadata_simple_iterator_init()
  454.  * \retval FLAC__bool
  455.  *    \c true if the current metadata block is the last in the file,
  456.  *    else \c false.
  457.  */
  458. FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_last(const FLAC__Metadata_SimpleIterator *iterator);
  459.  
  460. /** Get the offset of the metadata block at the current position.  This
  461.  *  avoids reading the actual block data which can save time for large
  462.  *  blocks.
  463.  *
  464.  * \param iterator  A pointer to an existing initialized iterator.
  465.  * \assert
  466.  *    \code iterator != NULL \endcode
  467.  *    \a iterator has been successfully initialized with
  468.  *    FLAC__metadata_simple_iterator_init()
  469.  * \retval off_t
  470.  *    The offset of the metadata block at the current iterator position.
  471.  *    This is the byte offset relative to the beginning of the file of
  472.  *    the current metadata block's header.
  473.  */
  474. FLAC_API off_t FLAC__metadata_simple_iterator_get_block_offset(const FLAC__Metadata_SimpleIterator *iterator);
  475.  
  476. /** Get the type of the metadata block at the current position.  This
  477.  *  avoids reading the actual block data which can save time for large
  478.  *  blocks.
  479.  *
  480.  * \param iterator  A pointer to an existing initialized iterator.
  481.  * \assert
  482.  *    \code iterator != NULL \endcode
  483.  *    \a iterator has been successfully initialized with
  484.  *    FLAC__metadata_simple_iterator_init()
  485.  * \retval FLAC__MetadataType
  486.  *    The type of the metadata block at the current iterator position.
  487.  */
  488. FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator);
  489.  
  490. /** Get the length of the metadata block at the current position.  This
  491.  *  avoids reading the actual block data which can save time for large
  492.  *  blocks.
  493.  *
  494.  * \param iterator  A pointer to an existing initialized iterator.
  495.  * \assert
  496.  *    \code iterator != NULL \endcode
  497.  *    \a iterator has been successfully initialized with
  498.  *    FLAC__metadata_simple_iterator_init()
  499.  * \retval unsigned
  500.  *    The length of the metadata block at the current iterator position.
  501.  *    The is same length as that in the
  502.  *    <a href="http://flac.sourceforge.net/format.html#metadata_block_header">metadata block header</a>,
  503.  *    i.e. the length of the metadata body that follows the header.
  504.  */
  505. FLAC_API unsigned FLAC__metadata_simple_iterator_get_block_length(const FLAC__Metadata_SimpleIterator *iterator);
  506.  
  507. /** Get the application ID of the \c APPLICATION block at the current
  508.  *  position.  This avoids reading the actual block data which can save
  509.  *  time for large blocks.
  510.  *
  511.  * \param iterator  A pointer to an existing initialized iterator.
  512.  * \param id        A pointer to a buffer of at least \c 4 bytes where
  513.  *                  the ID will be stored.
  514.  * \assert
  515.  *    \code iterator != NULL \endcode
  516.  *    \code id != NULL \endcode
  517.  *    \a iterator has been successfully initialized with
  518.  *    FLAC__metadata_simple_iterator_init()
  519.  * \retval FLAC__bool
  520.  *    \c true if the ID was successfully read, else \c false, in which
  521.  *    case you should check FLAC__metadata_simple_iterator_status() to
  522.  *    find out why.  If the status is
  523.  *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, then the
  524.  *    current metadata block is not an \c APPLICATION block.  Otherwise
  525.  *    if the status is
  526.  *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR or
  527.  *    \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, an I/O error
  528.  *    occurred and the iterator can no longer be used.
  529.  */
  530. FLAC_API FLAC__bool FLAC__metadata_simple_iterator_get_application_id(FLAC__Metadata_SimpleIterator *iterator, FLAC__byte *id);
  531.  
  532. /** Get the metadata block at the current position.  You can modify the
  533.  *  block but must use FLAC__metadata_simple_iterator_set_block() to
  534.  *  write it back to the FLAC file.
  535.  *
  536.  *  You must call FLAC__metadata_object_delete() on the returned object
  537.  *  when you are finished with it.
  538.  *
  539.  * \param iterator  A pointer to an existing initialized iterator.
  540.  * \assert
  541.  *    \code iterator != NULL \endcode
  542.  *    \a iterator has been successfully initialized with
  543.  *    FLAC__metadata_simple_iterator_init()
  544.  * \retval FLAC__StreamMetadata*
  545.  *    The current metadata block, or \c NULL if there was a memory
  546.  *    allocation error.
  547.  */
  548. FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator);
  549.  
  550. /** Write a block back to the FLAC file.  This function tries to be
  551.  *  as efficient as possible; how the block is actually written is
  552.  *  shown by the following:
  553.  *
  554.  *  Existing block is a STREAMINFO block and the new block is a
  555.  *  STREAMINFO block: the new block is written in place.  Make sure
  556.  *  you know what you're doing when changing the values of a
  557.  *  STREAMINFO block.
  558.  *
  559.  *  Existing block is a STREAMINFO block and the new block is a
  560.  *  not a STREAMINFO block: this is an error since the first block
  561.  *  must be a STREAMINFO block.  Returns \c false without altering the
  562.  *  file.
  563.  *
  564.  *  Existing block is not a STREAMINFO block and the new block is a
  565.  *  STREAMINFO block: this is an error since there may be only one
  566.  *  STREAMINFO block.  Returns \c false without altering the file.
  567.  *
  568.  *  Existing block and new block are the same length: the existing
  569.  *  block will be replaced by the new block, written in place.
  570.  *
  571.  *  Existing block is longer than new block: if use_padding is \c true,
  572.  *  the existing block will be overwritten in place with the new
  573.  *  block followed by a PADDING block, if possible, to make the total
  574.  *  size the same as the existing block.  Remember that a padding
  575.  *  block requires at least four bytes so if the difference in size
  576.  *  between the new block and existing block is less than that, the
  577.  *  entire file will have to be rewritten, using the new block's
  578.  *  exact size.  If use_padding is \c false, the entire file will be
  579.  *  rewritten, replacing the existing block by the new block.
  580.  *
  581.  *  Existing block is shorter than new block: if use_padding is \c true,
  582.  *  the function will try and expand the new block into the following
  583.  *  PADDING block, if it exists and doing so won't shrink the PADDING
  584.  *  block to less than 4 bytes.  If there is no following PADDING
  585.  *  block, or it will shrink to less than 4 bytes, or use_padding is
  586.  *  \c false, the entire file is rewritten, replacing the existing block
  587.  *  with the new block.  Note that in this case any following PADDING
  588.  *  block is preserved as is.
  589.  *
  590.  *  After writing the block, the iterator will remain in the same
  591.  *  place, i.e. pointing to the new block.
  592.  *
  593.  * \param iterator     A pointer to an existing initialized iterator.
  594.  * \param block        The block to set.
  595.  * \param use_padding  See above.
  596.  * \assert
  597.  *    \code iterator != NULL \endcode
  598.  *    \a iterator has been successfully initialized with
  599.  *    FLAC__metadata_simple_iterator_init()
  600.  *    \code block != NULL \endcode
  601.  * \retval FLAC__bool
  602.  *    \c true if successful, else \c false.
  603.  */
  604. FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
  605.  
  606. /** This is similar to FLAC__metadata_simple_iterator_set_block()
  607.  *  except that instead of writing over an existing block, it appends
  608.  *  a block after the existing block.  \a use_padding is again used to
  609.  *  tell the function to try an expand into following padding in an
  610.  *  attempt to avoid rewriting the entire file.
  611.  *
  612.  *  This function will fail and return \c false if given a STREAMINFO
  613.  *  block.
  614.  *
  615.  *  After writing the block, the iterator will be pointing to the
  616.  *  new block.
  617.  *
  618.  * \param iterator     A pointer to an existing initialized iterator.
  619.  * \param block        The block to set.
  620.  * \param use_padding  See above.
  621.  * \assert
  622.  *    \code iterator != NULL \endcode
  623.  *    \a iterator has been successfully initialized with
  624.  *    FLAC__metadata_simple_iterator_init()
  625.  *    \code block != NULL \endcode
  626.  * \retval FLAC__bool
  627.  *    \c true if successful, else \c false.
  628.  */
  629. FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
  630.  
  631. /** Deletes the block at the current position.  This will cause the
  632.  *  entire FLAC file to be rewritten, unless \a use_padding is \c true,
  633.  *  in which case the block will be replaced by an equal-sized PADDING
  634.  *  block.  The iterator will be left pointing to the block before the
  635.  *  one just deleted.
  636.  *
  637.  *  You may not delete the STREAMINFO block.
  638.  *
  639.  * \param iterator     A pointer to an existing initialized iterator.
  640.  * \param use_padding  See above.
  641.  * \assert
  642.  *    \code iterator != NULL \endcode
  643.  *    \a iterator has been successfully initialized with
  644.  *    FLAC__metadata_simple_iterator_init()
  645.  * \retval FLAC__bool
  646.  *    \c true if successful, else \c false.
  647.  */
  648. FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding);
  649.  
  650. /* \} */
  651.  
  652.  
  653. /** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface
  654.  *  \ingroup flac_metadata
  655.  *
  656.  * \brief
  657.  * The level 2 interface provides read-write access to FLAC file metadata;
  658.  * all metadata is read into memory, operated on in memory, and then written
  659.  * to file, which is more efficient than level 1 when editing multiple blocks.
  660.  *
  661.  * Currently Ogg FLAC is supported for read only, via
  662.  * FLAC__metadata_chain_read_ogg() but a subsequent
  663.  * FLAC__metadata_chain_write() will fail.
  664.  *
  665.  * The general usage of this interface is:
  666.  *
  667.  * - Create a new chain using FLAC__metadata_chain_new().  A chain is a
  668.  *   linked list of FLAC metadata blocks.
  669.  * - Read all metadata into the the chain from a FLAC file using
  670.  *   FLAC__metadata_chain_read() or FLAC__metadata_chain_read_ogg() and
  671.  *   check the status.
  672.  * - Optionally, consolidate the padding using
  673.  *   FLAC__metadata_chain_merge_padding() or
  674.  *   FLAC__metadata_chain_sort_padding().
  675.  * - Create a new iterator using FLAC__metadata_iterator_new()
  676.  * - Initialize the iterator to point to the first element in the chain
  677.  *   using FLAC__metadata_iterator_init()
  678.  * - Traverse the chain using FLAC__metadata_iterator_next and
  679.  *   FLAC__metadata_iterator_prev().
  680.  * - Get a block for reading or modification using
  681.  *   FLAC__metadata_iterator_get_block().  The pointer to the object
  682.  *   inside the chain is returned, so the block is yours to modify.
  683.  *   Changes will be reflected in the FLAC file when you write the
  684.  *   chain.  You can also add and delete blocks (see functions below).
  685.  * - When done, write out the chain using FLAC__metadata_chain_write().
  686.  *   Make sure to read the whole comment to the function below.
  687.  * - Delete the chain using FLAC__metadata_chain_delete().
  688.  *
  689.  * \note
  690.  * Even though the FLAC file is not open while the chain is being
  691.  * manipulated, you must not alter the file externally during
  692.  * this time.  The chain assumes the FLAC file will not change
  693.  * between the time of FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg()
  694.  * and FLAC__metadata_chain_write().
  695.  *
  696.  * \note
  697.  * Do not modify the is_last, length, or type fields of returned
  698.  * FLAC__StreamMetadata objects.  These are managed automatically.
  699.  *
  700.  * \note
  701.  * The metadata objects returned by FLAC__metadata_iterator_get_block()
  702.  * are owned by the chain; do not FLAC__metadata_object_delete() them.
  703.  * In the same way, blocks passed to FLAC__metadata_iterator_set_block()
  704.  * become owned by the chain and they will be deleted when the chain is
  705.  * deleted.
  706.  *
  707.  * \{
  708.  */
  709.  
  710. struct FLAC__Metadata_Chain;
  711. /** The opaque structure definition for the level 2 chain type.
  712.  */
  713. typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain;
  714.  
  715. struct FLAC__Metadata_Iterator;
  716. /** The opaque structure definition for the level 2 iterator type.
  717.  */
  718. typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator;
  719.  
  720. typedef enum {
  721.     FLAC__METADATA_CHAIN_STATUS_OK = 0,
  722.     /**< The chain is in the normal OK state */
  723.  
  724.     FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT,
  725.     /**< The data passed into a function violated the function's usage criteria */
  726.  
  727.     FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE,
  728.     /**< The chain could not open the target file */
  729.  
  730.     FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE,
  731.     /**< The chain could not find the FLAC signature at the start of the file */
  732.  
  733.     FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE,
  734.     /**< The chain tried to write to a file that was not writable */
  735.  
  736.     FLAC__METADATA_CHAIN_STATUS_BAD_METADATA,
  737.     /**< The chain encountered input that does not conform to the FLAC metadata specification */
  738.  
  739.     FLAC__METADATA_CHAIN_STATUS_READ_ERROR,
  740.     /**< The chain encountered an error while reading the FLAC file */
  741.  
  742.     FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR,
  743.     /**< The chain encountered an error while seeking in the FLAC file */
  744.  
  745.     FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR,
  746.     /**< The chain encountered an error while writing the FLAC file */
  747.  
  748.     FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR,
  749.     /**< The chain encountered an error renaming the FLAC file */
  750.  
  751.     FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR,
  752.     /**< The chain encountered an error removing the temporary file */
  753.  
  754.     FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR,
  755.     /**< Memory allocation failed */
  756.  
  757.     FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR,
  758.     /**< The caller violated an assertion or an unexpected error occurred */
  759.  
  760.     FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS,
  761.     /**< One or more of the required callbacks was NULL */
  762.  
  763.     FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH,
  764.     /**< FLAC__metadata_chain_write() was called on a chain read by
  765.      *   FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
  766.      *   or 
  767.      *   FLAC__metadata_chain_write_with_callbacks()/FLAC__metadata_chain_write_with_callbacks_and_tempfile()
  768.      *   was called on a chain read by
  769.      *   FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
  770.      *   Matching read/write methods must always be used. */
  771.  
  772.     FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL
  773.     /**< FLAC__metadata_chain_write_with_callbacks() was called when the
  774.      *   chain write requires a tempfile; use
  775.      *   FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead.
  776.      *   Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was
  777.      *   called when the chain write does not require a tempfile; use
  778.      *   FLAC__metadata_chain_write_with_callbacks() instead.
  779.      *   Always check FLAC__metadata_chain_check_if_tempfile_needed()
  780.      *   before writing via callbacks. */
  781.  
  782. } FLAC__Metadata_ChainStatus;
  783.  
  784. /** Maps a FLAC__Metadata_ChainStatus to a C string.
  785.  *
  786.  *  Using a FLAC__Metadata_ChainStatus as the index to this array
  787.  *  will give the string equivalent.  The contents should not be modified.
  788.  */
  789. extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[];
  790.  
  791. /*********** FLAC__Metadata_Chain ***********/
  792.  
  793. /** Create a new chain instance.
  794.  *
  795.  * \retval FLAC__Metadata_Chain*
  796.  *    \c NULL if there was an error allocating memory, else the new instance.
  797.  */
  798. FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(void);
  799.  
  800. /** Free a chain instance.  Deletes the object pointed to by \a chain.
  801.  *
  802.  * \param chain  A pointer to an existing chain.
  803.  * \assert
  804.  *    \code chain != NULL \endcode
  805.  */
  806. FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
  807.  
  808. /** Get the current status of the chain.  Call this after a function
  809.  *  returns \c false to get the reason for the error.  Also resets the
  810.  *  status to FLAC__METADATA_CHAIN_STATUS_OK.
  811.  *
  812.  * \param chain    A pointer to an existing chain.
  813.  * \assert
  814.  *    \code chain != NULL \endcode
  815.  * \retval FLAC__Metadata_ChainStatus
  816.  *    The current status of the chain.
  817.  */
  818. FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain);
  819.  
  820. /** Read all metadata from a FLAC file into the chain.
  821.  *
  822.  * \param chain    A pointer to an existing chain.
  823.  * \param filename The path to the FLAC file to read.
  824.  * \assert
  825.  *    \code chain != NULL \endcode
  826.  *    \code filename != NULL \endcode
  827.  * \retval FLAC__bool
  828.  *    \c true if a valid list of metadata blocks was read from
  829.  *    \a filename, else \c false.  On failure, check the status with
  830.  *    FLAC__metadata_chain_status().
  831.  */
  832. FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);
  833.  
  834. /** Read all metadata from an Ogg FLAC file into the chain.
  835.  *
  836.  * \note Ogg FLAC metadata data writing is not supported yet and
  837.  * FLAC__metadata_chain_write() will fail.
  838.  *
  839.  * \param chain    A pointer to an existing chain.
  840.  * \param filename The path to the Ogg FLAC file to read.
  841.  * \assert
  842.  *    \code chain != NULL \endcode
  843.  *    \code filename != NULL \endcode
  844.  * \retval FLAC__bool
  845.  *    \c true if a valid list of metadata blocks was read from
  846.  *    \a filename, else \c false.  On failure, check the status with
  847.  *    FLAC__metadata_chain_status().
  848.  */
  849. FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg(FLAC__Metadata_Chain *chain, const char *filename);
  850.  
  851. /** Read all metadata from a FLAC stream into the chain via I/O callbacks.
  852.  *
  853.  *  The \a handle need only be open for reading, but must be seekable.
  854.  *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
  855.  *  for Windows).
  856.  *
  857.  * \param chain    A pointer to an existing chain.
  858.  * \param handle   The I/O handle of the FLAC stream to read.  The
  859.  *                 handle will NOT be closed after the metadata is read;
  860.  *                 that is the duty of the caller.
  861.  * \param callbacks
  862.  *                 A set of callbacks to use for I/O.  The mandatory
  863.  *                 callbacks are \a read, \a seek, and \a tell.
  864.  * \assert
  865.  *    \code chain != NULL \endcode
  866.  * \retval FLAC__bool
  867.  *    \c true if a valid list of metadata blocks was read from
  868.  *    \a handle, else \c false.  On failure, check the status with
  869.  *    FLAC__metadata_chain_status().
  870.  */
  871. FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
  872.  
  873. /** Read all metadata from an Ogg FLAC stream into the chain via I/O callbacks.
  874.  *
  875.  *  The \a handle need only be open for reading, but must be seekable.
  876.  *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
  877.  *  for Windows).
  878.  *
  879.  * \note Ogg FLAC metadata data writing is not supported yet and
  880.  * FLAC__metadata_chain_write() will fail.
  881.  *
  882.  * \param chain    A pointer to an existing chain.
  883.  * \param handle   The I/O handle of the Ogg FLAC stream to read.  The
  884.  *                 handle will NOT be closed after the metadata is read;
  885.  *                 that is the duty of the caller.
  886.  * \param callbacks
  887.  *                 A set of callbacks to use for I/O.  The mandatory
  888.  *                 callbacks are \a read, \a seek, and \a tell.
  889.  * \assert
  890.  *    \code chain != NULL \endcode
  891.  * \retval FLAC__bool
  892.  *    \c true if a valid list of metadata blocks was read from
  893.  *    \a handle, else \c false.  On failure, check the status with
  894.  *    FLAC__metadata_chain_status().
  895.  */
  896. FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
  897.  
  898. /** Checks if writing the given chain would require the use of a
  899.  *  temporary file, or if it could be written in place.
  900.  *
  901.  *  Under certain conditions, padding can be utilized so that writing
  902.  *  edited metadata back to the FLAC file does not require rewriting the
  903.  *  entire file.  If rewriting is required, then a temporary workfile is
  904.  *  required.  When writing metadata using callbacks, you must check
  905.  *  this function to know whether to call
  906.  *  FLAC__metadata_chain_write_with_callbacks() or
  907.  *  FLAC__metadata_chain_write_with_callbacks_and_tempfile().  When
  908.  *  writing with FLAC__metadata_chain_write(), the temporary file is
  909.  *  handled internally.
  910.  *
  911.  * \param chain    A pointer to an existing chain.
  912.  * \param use_padding
  913.  *                 Whether or not padding will be allowed to be used
  914.  *                 during the write.  The value of \a use_padding given
  915.  *                 here must match the value later passed to
  916.  *                 FLAC__metadata_chain_write_with_callbacks() or
  917.  *                 FLAC__metadata_chain_write_with_callbacks_with_tempfile().
  918.  * \assert
  919.  *    \code chain != NULL \endcode
  920.  * \retval FLAC__bool
  921.  *    \c true if writing the current chain would require a tempfile, or
  922.  *    \c false if metadata can be written in place.
  923.  */
  924. FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding);
  925.  
  926. /** Write all metadata out to the FLAC file.  This function tries to be as
  927.  *  efficient as possible; how the metadata is actually written is shown by
  928.  *  the following:
  929.  *
  930.  *  If the current chain is the same size as the existing metadata, the new
  931.  *  data is written in place.
  932.  *
  933.  *  If the current chain is longer than the existing metadata, and
  934.  *  \a use_padding is \c true, and the last block is a PADDING block of
  935.  *  sufficient length, the function will truncate the final padding block
  936.  *  so that the overall size of the metadata is the same as the existing
  937.  *  metadata, and then just rewrite the metadata.  Otherwise, if not all of
  938.  *  the above conditions are met, the entire FLAC file must be rewritten.
  939.  *  If you want to use padding this way it is a good idea to call
  940.  *  FLAC__metadata_chain_sort_padding() first so that you have the maximum
  941.  *  amount of padding to work with, unless you need to preserve ordering
  942.  *  of the PADDING blocks for some reason.
  943.  *
  944.  *  If the current chain is shorter than the existing metadata, and
  945.  *  \a use_padding is \c true, and the final block is a PADDING block, the padding
  946.  *  is extended to make the overall size the same as the existing data.  If
  947.  *  \a use_padding is \c true and the last block is not a PADDING block, a new
  948.  *  PADDING block is added to the end of the new data to make it the same
  949.  *  size as the existing data (if possible, see the note to
  950.  *  FLAC__metadata_simple_iterator_set_block() about the four byte limit)
  951.  *  and the new data is written in place.  If none of the above apply or
  952.  *  \a use_padding is \c false, the entire FLAC file is rewritten.
  953.  *
  954.  *  If \a preserve_file_stats is \c true, the owner and modification time will
  955.  *  be preserved even if the FLAC file is written.
  956.  *
  957.  *  For this write function to be used, the chain must have been read with
  958.  *  FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(), not
  959.  *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks().
  960.  *
  961.  * \param chain               A pointer to an existing chain.
  962.  * \param use_padding         See above.
  963.  * \param preserve_file_stats See above.
  964.  * \assert
  965.  *    \code chain != NULL \endcode
  966.  * \retval FLAC__bool
  967.  *    \c true if the write succeeded, else \c false.  On failure,
  968.  *    check the status with FLAC__metadata_chain_status().
  969.  */
  970. FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats);
  971.  
  972. /** Write all metadata out to a FLAC stream via callbacks.
  973.  *
  974.  *  (See FLAC__metadata_chain_write() for the details on how padding is
  975.  *  used to write metadata in place if possible.)
  976.  *
  977.  *  The \a handle must be open for updating and be seekable.  The
  978.  *  equivalent minimum stdio fopen() file mode is \c "r+" (or \c "r+b"
  979.  *  for Windows).
  980.  *
  981.  *  For this write function to be used, the chain must have been read with
  982.  *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
  983.  *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
  984.  *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
  985.  *  \c false.
  986.  *
  987.  * \param chain        A pointer to an existing chain.
  988.  * \param use_padding  See FLAC__metadata_chain_write()
  989.  * \param handle       The I/O handle of the FLAC stream to write.  The
  990.  *                     handle will NOT be closed after the metadata is
  991.  *                     written; that is the duty of the caller.
  992.  * \param callbacks    A set of callbacks to use for I/O.  The mandatory
  993.  *                     callbacks are \a write and \a seek.
  994.  * \assert
  995.  *    \code chain != NULL \endcode
  996.  * \retval FLAC__bool
  997.  *    \c true if the write succeeded, else \c false.  On failure,
  998.  *    check the status with FLAC__metadata_chain_status().
  999.  */
  1000. FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
  1001.  
  1002. /** Write all metadata out to a FLAC stream via callbacks.
  1003.  *
  1004.  *  (See FLAC__metadata_chain_write() for the details on how padding is
  1005.  *  used to write metadata in place if possible.)
  1006.  *
  1007.  *  This version of the write-with-callbacks function must be used when
  1008.  *  FLAC__metadata_chain_check_if_tempfile_needed() returns true.  In
  1009.  *  this function, you must supply an I/O handle corresponding to the
  1010.  *  FLAC file to edit, and a temporary handle to which the new FLAC
  1011.  *  file will be written.  It is the caller's job to move this temporary
  1012.  *  FLAC file on top of the original FLAC file to complete the metadata
  1013.  *  edit.
  1014.  *
  1015.  *  The \a handle must be open for reading and be seekable.  The
  1016.  *  equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
  1017.  *  for Windows).
  1018.  *
  1019.  *  The \a temp_handle must be open for writing.  The
  1020.  *  equivalent minimum stdio fopen() file mode is \c "w" (or \c "wb"
  1021.  *  for Windows).  It should be an empty stream, or at least positioned
  1022.  *  at the start-of-file (in which case it is the caller's duty to
  1023.  *  truncate it on return).
  1024.  *
  1025.  *  For this write function to be used, the chain must have been read with
  1026.  *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
  1027.  *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
  1028.  *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
  1029.  *  \c true.
  1030.  *
  1031.  * \param chain        A pointer to an existing chain.
  1032.  * \param use_padding  See FLAC__metadata_chain_write()
  1033.  * \param handle       The I/O handle of the original FLAC stream to read.
  1034.  *                     The handle will NOT be closed after the metadata is
  1035.  *                     written; that is the duty of the caller.
  1036.  * \param callbacks    A set of callbacks to use for I/O on \a handle.
  1037.  *                     The mandatory callbacks are \a read, \a seek, and
  1038.  *                     \a eof.
  1039.  * \param temp_handle  The I/O handle of the FLAC stream to write.  The
  1040.  *                     handle will NOT be closed after the metadata is
  1041.  *                     written; that is the duty of the caller.
  1042.  * \param temp_callbacks
  1043.  *                     A set of callbacks to use for I/O on temp_handle.
  1044.  *                     The only mandatory callback is \a write.
  1045.  * \assert
  1046.  *    \code chain != NULL \endcode
  1047.  * \retval FLAC__bool
  1048.  *    \c true if the write succeeded, else \c false.  On failure,
  1049.  *    check the status with FLAC__metadata_chain_status().
  1050.  */
  1051. FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks_and_tempfile(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks, FLAC__IOHandle temp_handle, FLAC__IOCallbacks temp_callbacks);
  1052.  
  1053. /** Merge adjacent PADDING blocks into a single block.
  1054.  *
  1055.  * \note This function does not write to the FLAC file, it only
  1056.  * modifies the chain.
  1057.  *
  1058.  * \warning Any iterator on the current chain will become invalid after this
  1059.  * call.  You should delete the iterator and get a new one.
  1060.  *
  1061.  * \param chain               A pointer to an existing chain.
  1062.  * \assert
  1063.  *    \code chain != NULL \endcode
  1064.  */
  1065. FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
  1066.  
  1067. /** This function will move all PADDING blocks to the end on the metadata,
  1068.  *  then merge them into a single block.
  1069.  *
  1070.  * \note This function does not write to the FLAC file, it only
  1071.  * modifies the chain.
  1072.  *
  1073.  * \warning Any iterator on the current chain will become invalid after this
  1074.  * call.  You should delete the iterator and get a new one.
  1075.  *
  1076.  * \param chain  A pointer to an existing chain.
  1077.  * \assert
  1078.  *    \code chain != NULL \endcode
  1079.  */
  1080. FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain);
  1081.  
  1082.  
  1083. /*********** FLAC__Metadata_Iterator ***********/
  1084.  
  1085. /** Create a new iterator instance.
  1086.  *
  1087.  * \retval FLAC__Metadata_Iterator*
  1088.  *    \c NULL if there was an error allocating memory, else the new instance.
  1089.  */
  1090. FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(void);
  1091.  
  1092. /** Free an iterator instance.  Deletes the object pointed to by \a iterator.
  1093.  *
  1094.  * \param iterator  A pointer to an existing iterator.
  1095.  * \assert
  1096.  *    \code iterator != NULL \endcode
  1097.  */
  1098. FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
  1099.  
  1100. /** Initialize the iterator to point to the first metadata block in the
  1101.  *  given chain.
  1102.  *
  1103.  * \param iterator  A pointer to an existing iterator.
  1104.  * \param chain     A pointer to an existing and initialized (read) chain.
  1105.  * \assert
  1106.  *    \code iterator != NULL \endcode
  1107.  *    \code chain != NULL \endcode
  1108.  */
  1109. FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain);
  1110.  
  1111. /** Moves the iterator forward one metadata block, returning \c false if
  1112.  *  already at the end.
  1113.  *
  1114.  * \param iterator  A pointer to an existing initialized iterator.
  1115.  * \assert
  1116.  *    \code iterator != NULL \endcode
  1117.  *    \a iterator has been successfully initialized with
  1118.  *    FLAC__metadata_iterator_init()
  1119.  * \retval FLAC__bool
  1120.  *    \c false if already at the last metadata block of the chain, else
  1121.  *    \c true.
  1122.  */
  1123. FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator);
  1124.  
  1125. /** Moves the iterator backward one metadata block, returning \c false if
  1126.  *  already at the beginning.
  1127.  *
  1128.  * \param iterator  A pointer to an existing initialized iterator.
  1129.  * \assert
  1130.  *    \code iterator != NULL \endcode
  1131.  *    \a iterator has been successfully initialized with
  1132.  *    FLAC__metadata_iterator_init()
  1133.  * \retval FLAC__bool
  1134.  *    \c false if already at the first metadata block of the chain, else
  1135.  *    \c true.
  1136.  */
  1137. FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator);
  1138.  
  1139. /** Get the type of the metadata block at the current position.
  1140.  *
  1141.  * \param iterator  A pointer to an existing initialized iterator.
  1142.  * \assert
  1143.  *    \code iterator != NULL \endcode
  1144.  *    \a iterator has been successfully initialized with
  1145.  *    FLAC__metadata_iterator_init()
  1146.  * \retval FLAC__MetadataType
  1147.  *    The type of the metadata block at the current iterator position.
  1148.  */
  1149. FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator);
  1150.  
  1151. /** Get the metadata block at the current position.  You can modify
  1152.  *  the block in place but must write the chain before the changes
  1153.  *  are reflected to the FLAC file.  You do not need to call
  1154.  *  FLAC__metadata_iterator_set_block() to reflect the changes;
  1155.  *  the pointer returned by FLAC__metadata_iterator_get_block()
  1156.  *  points directly into the chain.
  1157.  *
  1158.  * \warning
  1159.  * Do not call FLAC__metadata_object_delete() on the returned object;
  1160.  * to delete a block use FLAC__metadata_iterator_delete_block().
  1161.  *
  1162.  * \param iterator  A pointer to an existing initialized iterator.
  1163.  * \assert
  1164.  *    \code iterator != NULL \endcode
  1165.  *    \a iterator has been successfully initialized with
  1166.  *    FLAC__metadata_iterator_init()
  1167.  * \retval FLAC__StreamMetadata*
  1168.  *    The current metadata block.
  1169.  */
  1170. FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator);
  1171.  
  1172. /** Set the metadata block at the current position, replacing the existing
  1173.  *  block.  The new block passed in becomes owned by the chain and it will be
  1174.  *  deleted when the chain is deleted.
  1175.  *
  1176.  * \param iterator  A pointer to an existing initialized iterator.
  1177.  * \param block     A pointer to a metadata block.
  1178.  * \assert
  1179.  *    \code iterator != NULL \endcode
  1180.  *    \a iterator has been successfully initialized with
  1181.  *    FLAC__metadata_iterator_init()
  1182.  *    \code block != NULL \endcode
  1183.  * \retval FLAC__bool
  1184.  *    \c false if the conditions in the above description are not met, or
  1185.  *    a memory allocation error occurs, otherwise \c true.
  1186.  */
  1187. FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
  1188.  
  1189. /** Removes the current block from the chain.  If \a replace_with_padding is
  1190.  *  \c true, the block will instead be replaced with a padding block of equal
  1191.  *  size.  You can not delete the STREAMINFO block.  The iterator will be
  1192.  *  left pointing to the block before the one just "deleted", even if
  1193.  *  \a replace_with_padding is \c true.
  1194.  *
  1195.  * \param iterator              A pointer to an existing initialized iterator.
  1196.  * \param replace_with_padding  See above.
  1197.  * \assert
  1198.  *    \code iterator != NULL \endcode
  1199.  *    \a iterator has been successfully initialized with
  1200.  *    FLAC__metadata_iterator_init()
  1201.  * \retval FLAC__bool
  1202.  *    \c false if the conditions in the above description are not met,
  1203.  *    otherwise \c true.
  1204.  */
  1205. FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding);
  1206.  
  1207. /** Insert a new block before the current block.  You cannot insert a block
  1208.  *  before the first STREAMINFO block.  You cannot insert a STREAMINFO block
  1209.  *  as there can be only one, the one that already exists at the head when you
  1210.  *  read in a chain.  The chain takes ownership of the new block and it will be
  1211.  *  deleted when the chain is deleted.  The iterator will be left pointing to
  1212.  *  the new block.
  1213.  *
  1214.  * \param iterator  A pointer to an existing initialized iterator.
  1215.  * \param block     A pointer to a metadata block to insert.
  1216.  * \assert
  1217.  *    \code iterator != NULL \endcode
  1218.  *    \a iterator has been successfully initialized with
  1219.  *    FLAC__metadata_iterator_init()
  1220.  * \retval FLAC__bool
  1221.  *    \c false if the conditions in the above description are not met, or
  1222.  *    a memory allocation error occurs, otherwise \c true.
  1223.  */
  1224. FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
  1225.  
  1226. /** Insert a new block after the current block.  You cannot insert a STREAMINFO
  1227.  *  block as there can be only one, the one that already exists at the head when
  1228.  *  you read in a chain.  The chain takes ownership of the new block and it will
  1229.  *  be deleted when the chain is deleted.  The iterator will be left pointing to
  1230.  *  the new block.
  1231.  *
  1232.  * \param iterator  A pointer to an existing initialized iterator.
  1233.  * \param block     A pointer to a metadata block to insert.
  1234.  * \assert
  1235.  *    \code iterator != NULL \endcode
  1236.  *    \a iterator has been successfully initialized with
  1237.  *    FLAC__metadata_iterator_init()
  1238.  * \retval FLAC__bool
  1239.  *    \c false if the conditions in the above description are not met, or
  1240.  *    a memory allocation error occurs, otherwise \c true.
  1241.  */
  1242. FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
  1243.  
  1244. /* \} */
  1245.  
  1246.  
  1247. /** \defgroup flac_metadata_object FLAC/metadata.h: metadata object methods
  1248.  *  \ingroup flac_metadata
  1249.  *
  1250.  * \brief
  1251.  * This module contains methods for manipulating FLAC metadata objects.
  1252.  *
  1253.  * Since many are variable length we have to be careful about the memory
  1254.  * management.  We decree that all pointers to data in the object are
  1255.  * owned by the object and memory-managed by the object.
  1256.  *
  1257.  * Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete()
  1258.  * functions to create all instances.  When using the
  1259.  * FLAC__metadata_object_set_*() functions to set pointers to data, set
  1260.  * \a copy to \c true to have the function make it's own copy of the data, or
  1261.  * to \c false to give the object ownership of your data.  In the latter case
  1262.  * your pointer must be freeable by free() and will be free()d when the object
  1263.  * is FLAC__metadata_object_delete()d.  It is legal to pass a null pointer as
  1264.  * the data pointer to a FLAC__metadata_object_set_*() function as long as
  1265.  * the length argument is 0 and the \a copy argument is \c false.
  1266.  *
  1267.  * The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function
  1268.  * will return \c NULL in the case of a memory allocation error, otherwise a new
  1269.  * object.  The FLAC__metadata_object_set_*() functions return \c false in the
  1270.  * case of a memory allocation error.
  1271.  *
  1272.  * We don't have the convenience of C++ here, so note that the library relies
  1273.  * on you to keep the types straight.  In other words, if you pass, for
  1274.  * example, a FLAC__StreamMetadata* that represents a STREAMINFO block to
  1275.  * FLAC__metadata_object_application_set_data(), you will get an assertion
  1276.  * failure.
  1277.  *
  1278.  * For convenience the FLAC__metadata_object_vorbiscomment_*() functions
  1279.  * maintain a trailing NUL on each Vorbis comment entry.  This is not counted
  1280.  * toward the length or stored in the stream, but it can make working with plain
  1281.  * comments (those that don't contain embedded-NULs in the value) easier.
  1282.  * Entries passed into these functions have trailing NULs added if missing, and
  1283.  * returned entries are guaranteed to have a trailing NUL.
  1284.  *
  1285.  * The FLAC__metadata_object_vorbiscomment_*() functions that take a Vorbis
  1286.  * comment entry/name/value will first validate that it complies with the Vorbis
  1287.  * comment specification and return false if it does not.
  1288.  *
  1289.  * There is no need to recalculate the length field on metadata blocks you
  1290.  * have modified.  They will be calculated automatically before they  are
  1291.  * written back to a file.
  1292.  *
  1293.  * \{
  1294.  */
  1295.  
  1296.  
  1297. /** Create a new metadata object instance of the given type.
  1298.  *
  1299.  *  The object will be "empty"; i.e. values and data pointers will be \c 0,
  1300.  *  with the exception of FLAC__METADATA_TYPE_VORBIS_COMMENT, which will have
  1301.  *  the vendor string set (but zero comments).
  1302.  *
  1303.  *  Do not pass in a value greater than or equal to
  1304.  *  \a FLAC__METADATA_TYPE_UNDEFINED unless you really know what you're
  1305.  *  doing.
  1306.  *
  1307.  * \param type  Type of object to create
  1308.  * \retval FLAC__StreamMetadata*
  1309.  *    \c NULL if there was an error allocating memory or the type code is
  1310.  *    greater than FLAC__MAX_METADATA_TYPE_CODE, else the new instance.
  1311.  */
  1312. FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type);
  1313.  
  1314. /** Create a copy of an existing metadata object.
  1315.  *
  1316.  *  The copy is a "deep" copy, i.e. dynamically allocated data within the
  1317.  *  object is also copied.  The caller takes ownership of the new block and
  1318.  *  is responsible for freeing it with FLAC__metadata_object_delete().
  1319.  *
  1320.  * \param object  Pointer to object to copy.
  1321.  * \assert
  1322.  *    \code object != NULL \endcode
  1323.  * \retval FLAC__StreamMetadata*
  1324.  *    \c NULL if there was an error allocating memory, else the new instance.
  1325.  */
  1326. FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object);
  1327.  
  1328. /** Free a metadata object.  Deletes the object pointed to by \a object.
  1329.  *
  1330.  *  The delete is a "deep" delete, i.e. dynamically allocated data within the
  1331.  *  object is also deleted.
  1332.  *
  1333.  * \param object  A pointer to an existing object.
  1334.  * \assert
  1335.  *    \code object != NULL \endcode
  1336.  */
  1337. FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
  1338.  
  1339. /** Compares two metadata objects.
  1340.  *
  1341.  *  The compare is "deep", i.e. dynamically allocated data within the
  1342.  *  object is also compared.
  1343.  *
  1344.  * \param block1  A pointer to an existing object.
  1345.  * \param block2  A pointer to an existing object.
  1346.  * \assert
  1347.  *    \code block1 != NULL \endcode
  1348.  *    \code block2 != NULL \endcode
  1349.  * \retval FLAC__bool
  1350.  *    \c true if objects are identical, else \c false.
  1351.  */
  1352. FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2);
  1353.  
  1354. /** Sets the application data of an APPLICATION block.
  1355.  *
  1356.  *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
  1357.  *  takes ownership of the pointer.  The existing data will be freed if this
  1358.  *  function is successful, otherwise the original data will remain if \a copy
  1359.  *  is \c true and malloc() fails.
  1360.  *
  1361.  * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
  1362.  *
  1363.  * \param object  A pointer to an existing APPLICATION object.
  1364.  * \param data    A pointer to the data to set.
  1365.  * \param length  The length of \a data in bytes.
  1366.  * \param copy    See above.
  1367.  * \assert
  1368.  *    \code object != NULL \endcode
  1369.  *    \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode
  1370.  *    \code (data != NULL && length > 0) ||
  1371.  * (data == NULL && length == 0 && copy == false) \endcode
  1372.  * \retval FLAC__bool
  1373.  *    \c false if \a copy is \c true and malloc() fails, else \c true.
  1374.  */
  1375. FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy);
  1376.  
  1377. /** Resize the seekpoint array.
  1378.  *
  1379.  *  If the size shrinks, elements will truncated; if it grows, new placeholder
  1380.  *  points will be added to the end.
  1381.  *
  1382.  * \param object          A pointer to an existing SEEKTABLE object.
  1383.  * \param new_num_points  The desired length of the array; may be \c 0.
  1384.  * \assert
  1385.  *    \code object != NULL \endcode
  1386.  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1387.  *    \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) ||
  1388.  * (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode
  1389.  * \retval FLAC__bool
  1390.  *    \c false if memory allocation error, else \c true.
  1391.  */
  1392. FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points);
  1393.  
  1394. /** Set a seekpoint in a seektable.
  1395.  *
  1396.  * \param object     A pointer to an existing SEEKTABLE object.
  1397.  * \param point_num  Index into seekpoint array to set.
  1398.  * \param point      The point to set.
  1399.  * \assert
  1400.  *    \code object != NULL \endcode
  1401.  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1402.  *    \code object->data.seek_table.num_points > point_num \endcode
  1403.  */
  1404. FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
  1405.  
  1406. /** Insert a seekpoint into a seektable.
  1407.  *
  1408.  * \param object     A pointer to an existing SEEKTABLE object.
  1409.  * \param point_num  Index into seekpoint array to set.
  1410.  * \param point      The point to set.
  1411.  * \assert
  1412.  *    \code object != NULL \endcode
  1413.  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1414.  *    \code object->data.seek_table.num_points >= point_num \endcode
  1415.  * \retval FLAC__bool
  1416.  *    \c false if memory allocation error, else \c true.
  1417.  */
  1418. FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
  1419.  
  1420. /** Delete a seekpoint from a seektable.
  1421.  *
  1422.  * \param object     A pointer to an existing SEEKTABLE object.
  1423.  * \param point_num  Index into seekpoint array to set.
  1424.  * \assert
  1425.  *    \code object != NULL \endcode
  1426.  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1427.  *    \code object->data.seek_table.num_points > point_num \endcode
  1428.  * \retval FLAC__bool
  1429.  *    \c false if memory allocation error, else \c true.
  1430.  */
  1431. FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num);
  1432.  
  1433. /** Check a seektable to see if it conforms to the FLAC specification.
  1434.  *  See the format specification for limits on the contents of the
  1435.  *  seektable.
  1436.  *
  1437.  * \param object  A pointer to an existing SEEKTABLE object.
  1438.  * \assert
  1439.  *    \code object != NULL \endcode
  1440.  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1441.  * \retval FLAC__bool
  1442.  *    \c false if seek table is illegal, else \c true.
  1443.  */
  1444. FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
  1445.  
  1446. /** Append a number of placeholder points to the end of a seek table.
  1447.  *
  1448.  * \note
  1449.  * As with the other ..._seektable_template_... functions, you should
  1450.  * call FLAC__metadata_object_seektable_template_sort() when finished
  1451.  * to make the seek table legal.
  1452.  *
  1453.  * \param object  A pointer to an existing SEEKTABLE object.
  1454.  * \param num     The number of placeholder points to append.
  1455.  * \assert
  1456.  *    \code object != NULL \endcode
  1457.  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1458.  * \retval FLAC__bool
  1459.  *    \c false if memory allocation fails, else \c true.
  1460.  */
  1461. FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num);
  1462.  
  1463. /** Append a specific seek point template to the end of a seek table.
  1464.  *
  1465.  * \note
  1466.  * As with the other ..._seektable_template_... functions, you should
  1467.  * call FLAC__metadata_object_seektable_template_sort() when finished
  1468.  * to make the seek table legal.
  1469.  *
  1470.  * \param object  A pointer to an existing SEEKTABLE object.
  1471.  * \param sample_number  The sample number of the seek point template.
  1472.  * \assert
  1473.  *    \code object != NULL \endcode
  1474.  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1475.  * \retval FLAC__bool
  1476.  *    \c false if memory allocation fails, else \c true.
  1477.  */
  1478. FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number);
  1479.  
  1480. /** Append specific seek point templates to the end of a seek table.
  1481.  *
  1482.  * \note
  1483.  * As with the other ..._seektable_template_... functions, you should
  1484.  * call FLAC__metadata_object_seektable_template_sort() when finished
  1485.  * to make the seek table legal.
  1486.  *
  1487.  * \param object  A pointer to an existing SEEKTABLE object.
  1488.  * \param sample_numbers  An array of sample numbers for the seek points.
  1489.  * \param num     The number of seek point templates to append.
  1490.  * \assert
  1491.  *    \code object != NULL \endcode
  1492.  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1493.  * \retval FLAC__bool
  1494.  *    \c false if memory allocation fails, else \c true.
  1495.  */
  1496. FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num);
  1497.  
  1498. /** Append a set of evenly-spaced seek point templates to the end of a
  1499.  *  seek table.
  1500.  *
  1501.  * \note
  1502.  * As with the other ..._seektable_template_... functions, you should
  1503.  * call FLAC__metadata_object_seektable_template_sort() when finished
  1504.  * to make the seek table legal.
  1505.  *
  1506.  * \param object  A pointer to an existing SEEKTABLE object.
  1507.  * \param num     The number of placeholder points to append.
  1508.  * \param total_samples  The total number of samples to be encoded;
  1509.  *                       the seekpoints will be spaced approximately
  1510.  *                       \a total_samples / \a num samples apart.
  1511.  * \assert
  1512.  *    \code object != NULL \endcode
  1513.  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1514.  *    \code total_samples > 0 \endcode
  1515.  * \retval FLAC__bool
  1516.  *    \c false if memory allocation fails, else \c true.
  1517.  */
  1518. FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
  1519.  
  1520. /** Append a set of evenly-spaced seek point templates to the end of a
  1521.  *  seek table.
  1522.  *
  1523.  * \note
  1524.  * As with the other ..._seektable_template_... functions, you should
  1525.  * call FLAC__metadata_object_seektable_template_sort() when finished
  1526.  * to make the seek table legal.
  1527.  *
  1528.  * \param object  A pointer to an existing SEEKTABLE object.
  1529.  * \param samples The number of samples apart to space the placeholder
  1530.  *                points.  The first point will be at sample \c 0, the
  1531.  *                second at sample \a samples, then 2*\a samples, and
  1532.  *                so on.  As long as \a samples and \a total_samples
  1533.  *                are greater than \c 0, there will always be at least
  1534.  *                one seekpoint at sample \c 0.
  1535.  * \param total_samples  The total number of samples to be encoded;
  1536.  *                       the seekpoints will be spaced
  1537.  *                       \a samples samples apart.
  1538.  * \assert
  1539.  *    \code object != NULL \endcode
  1540.  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1541.  *    \code samples > 0 \endcode
  1542.  *    \code total_samples > 0 \endcode
  1543.  * \retval FLAC__bool
  1544.  *    \c false if memory allocation fails, else \c true.
  1545.  */
  1546. FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples);
  1547.  
  1548. /** Sort a seek table's seek points according to the format specification,
  1549.  *  removing duplicates.
  1550.  *
  1551.  * \param object   A pointer to a seek table to be sorted.
  1552.  * \param compact  If \c false, behaves like FLAC__format_seektable_sort().
  1553.  *                 If \c true, duplicates are deleted and the seek table is
  1554.  *                 shrunk appropriately; the number of placeholder points
  1555.  *                 present in the seek table will be the same after the call
  1556.  *                 as before.
  1557.  * \assert
  1558.  *    \code object != NULL \endcode
  1559.  *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
  1560.  * \retval FLAC__bool
  1561.  *    \c false if realloc() fails, else \c true.
  1562.  */
  1563. FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact);
  1564.  
  1565. /** Sets the vendor string in a VORBIS_COMMENT block.
  1566.  *
  1567.  *  For convenience, a trailing NUL is added to the entry if it doesn't have
  1568.  *  one already.
  1569.  *
  1570.  *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  1571.  *  takes ownership of the \c entry.entry pointer.
  1572.  *
  1573.  *  \note If this function returns \c false, the caller still owns the
  1574.  *  pointer.
  1575.  *
  1576.  * \param object  A pointer to an existing VORBIS_COMMENT object.
  1577.  * \param entry   The entry to set the vendor string to.
  1578.  * \param copy    See above.
  1579.  * \assert
  1580.  *    \code object != NULL \endcode
  1581.  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1582.  *    \code (entry.entry != NULL && entry.length > 0) ||
  1583.  * (entry.entry == NULL && entry.length == 0) \endcode
  1584.  * \retval FLAC__bool
  1585.  *    \c false if memory allocation fails or \a entry does not comply with the
  1586.  *    Vorbis comment specification, else \c true.
  1587.  */
  1588. FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  1589.  
  1590. /** Resize the comment array.
  1591.  *
  1592.  *  If the size shrinks, elements will truncated; if it grows, new empty
  1593.  *  fields will be added to the end.
  1594.  *
  1595.  * \param object            A pointer to an existing VORBIS_COMMENT object.
  1596.  * \param new_num_comments  The desired length of the array; may be \c 0.
  1597.  * \assert
  1598.  *    \code object != NULL \endcode
  1599.  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1600.  *    \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) ||
  1601.  * (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode
  1602.  * \retval FLAC__bool
  1603.  *    \c false if memory allocation fails, else \c true.
  1604.  */
  1605. FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
  1606.  
  1607. /** Sets a comment in a VORBIS_COMMENT block.
  1608.  *
  1609.  *  For convenience, a trailing NUL is added to the entry if it doesn't have
  1610.  *  one already.
  1611.  *
  1612.  *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  1613.  *  takes ownership of the \c entry.entry pointer.
  1614.  *
  1615.  *  \note If this function returns \c false, the caller still owns the
  1616.  *  pointer.
  1617.  *
  1618.  * \param object       A pointer to an existing VORBIS_COMMENT object.
  1619.  * \param comment_num  Index into comment array to set.
  1620.  * \param entry        The entry to set the comment to.
  1621.  * \param copy         See above.
  1622.  * \assert
  1623.  *    \code object != NULL \endcode
  1624.  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1625.  *    \code comment_num < object->data.vorbis_comment.num_comments \endcode
  1626.  *    \code (entry.entry != NULL && entry.length > 0) ||
  1627.  * (entry.entry == NULL && entry.length == 0) \endcode
  1628.  * \retval FLAC__bool
  1629.  *    \c false if memory allocation fails or \a entry does not comply with the
  1630.  *    Vorbis comment specification, else \c true.
  1631.  */
  1632. FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  1633.  
  1634. /** Insert a comment in a VORBIS_COMMENT block at the given index.
  1635.  *
  1636.  *  For convenience, a trailing NUL is added to the entry if it doesn't have
  1637.  *  one already.
  1638.  *
  1639.  *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  1640.  *  takes ownership of the \c entry.entry pointer.
  1641.  *
  1642.  *  \note If this function returns \c false, the caller still owns the
  1643.  *  pointer.
  1644.  *
  1645.  * \param object       A pointer to an existing VORBIS_COMMENT object.
  1646.  * \param comment_num  The index at which to insert the comment.  The comments
  1647.  *                     at and after \a comment_num move right one position.
  1648.  *                     To append a comment to the end, set \a comment_num to
  1649.  *                     \c object->data.vorbis_comment.num_comments .
  1650.  * \param entry        The comment to insert.
  1651.  * \param copy         See above.
  1652.  * \assert
  1653.  *    \code object != NULL \endcode
  1654.  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1655.  *    \code object->data.vorbis_comment.num_comments >= comment_num \endcode
  1656.  *    \code (entry.entry != NULL && entry.length > 0) ||
  1657.  * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
  1658.  * \retval FLAC__bool
  1659.  *    \c false if memory allocation fails or \a entry does not comply with the
  1660.  *    Vorbis comment specification, else \c true.
  1661.  */
  1662. FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  1663.  
  1664. /** Appends a comment to a VORBIS_COMMENT block.
  1665.  *
  1666.  *  For convenience, a trailing NUL is added to the entry if it doesn't have
  1667.  *  one already.
  1668.  *
  1669.  *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  1670.  *  takes ownership of the \c entry.entry pointer.
  1671.  *
  1672.  *  \note If this function returns \c false, the caller still owns the
  1673.  *  pointer.
  1674.  *
  1675.  * \param object       A pointer to an existing VORBIS_COMMENT object.
  1676.  * \param entry        The comment to insert.
  1677.  * \param copy         See above.
  1678.  * \assert
  1679.  *    \code object != NULL \endcode
  1680.  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1681.  *    \code (entry.entry != NULL && entry.length > 0) ||
  1682.  * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
  1683.  * \retval FLAC__bool
  1684.  *    \c false if memory allocation fails or \a entry does not comply with the
  1685.  *    Vorbis comment specification, else \c true.
  1686.  */
  1687. FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
  1688.  
  1689. /** Replaces comments in a VORBIS_COMMENT block with a new one.
  1690.  *
  1691.  *  For convenience, a trailing NUL is added to the entry if it doesn't have
  1692.  *  one already.
  1693.  *
  1694.  *  Depending on the the value of \a all, either all or just the first comment
  1695.  *  whose field name(s) match the given entry's name will be replaced by the
  1696.  *  given entry.  If no comments match, \a entry will simply be appended.
  1697.  *
  1698.  *  If \a copy is \c true, a copy of the entry is stored; otherwise, the object
  1699.  *  takes ownership of the \c entry.entry pointer.
  1700.  *
  1701.  *  \note If this function returns \c false, the caller still owns the
  1702.  *  pointer.
  1703.  *
  1704.  * \param object       A pointer to an existing VORBIS_COMMENT object.
  1705.  * \param entry        The comment to insert.
  1706.  * \param all          If \c true, all comments whose field name matches
  1707.  *                     \a entry's field name will be removed, and \a entry will
  1708.  *                     be inserted at the position of the first matching
  1709.  *                     comment.  If \c false, only the first comment whose
  1710.  *                     field name matches \a entry's field name will be
  1711.  *                     replaced with \a entry.
  1712.  * \param copy         See above.
  1713.  * \assert
  1714.  *    \code object != NULL \endcode
  1715.  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1716.  *    \code (entry.entry != NULL && entry.length > 0) ||
  1717.  * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
  1718.  * \retval FLAC__bool
  1719.  *    \c false if memory allocation fails or \a entry does not comply with the
  1720.  *    Vorbis comment specification, else \c true.
  1721.  */
  1722. FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy);
  1723.  
  1724. /** Delete a comment in a VORBIS_COMMENT block at the given index.
  1725.  *
  1726.  * \param object       A pointer to an existing VORBIS_COMMENT object.
  1727.  * \param comment_num  The index of the comment to delete.
  1728.  * \assert
  1729.  *    \code object != NULL \endcode
  1730.  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1731.  *    \code object->data.vorbis_comment.num_comments > comment_num \endcode
  1732.  * \retval FLAC__bool
  1733.  *    \c false if realloc() fails, else \c true.
  1734.  */
  1735. FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num);
  1736.  
  1737. /** Creates a Vorbis comment entry from NUL-terminated name and value strings.
  1738.  *
  1739.  *  On return, the filled-in \a entry->entry pointer will point to malloc()ed
  1740.  *  memory and shall be owned by the caller.  For convenience the entry will
  1741.  *  have a terminating NUL.
  1742.  *
  1743.  * \param entry              A pointer to a Vorbis comment entry.  The entry's
  1744.  *                           \c entry pointer should not point to allocated
  1745.  *                           memory as it will be overwritten.
  1746.  * \param field_name         The field name in ASCII, \c NUL terminated.
  1747.  * \param field_value        The field value in UTF-8, \c NUL terminated.
  1748.  * \assert
  1749.  *    \code entry != NULL \endcode
  1750.  *    \code field_name != NULL \endcode
  1751.  *    \code field_value != NULL \endcode
  1752.  * \retval FLAC__bool
  1753.  *    \c false if malloc() fails, or if \a field_name or \a field_value does
  1754.  *    not comply with the Vorbis comment specification, else \c true.
  1755.  */
  1756. FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_from_name_value_pair(FLAC__StreamMetadata_VorbisComment_Entry *entry, const char *field_name, const char *field_value);
  1757.  
  1758. /** Splits a Vorbis comment entry into NUL-terminated name and value strings.
  1759.  *
  1760.  *  The returned pointers to name and value will be allocated by malloc()
  1761.  *  and shall be owned by the caller.
  1762.  *
  1763.  * \param entry              An existing Vorbis comment entry.
  1764.  * \param field_name         The address of where the returned pointer to the
  1765.  *                           field name will be stored.
  1766.  * \param field_value        The address of where the returned pointer to the
  1767.  *                           field value will be stored.
  1768.  * \assert
  1769.  *    \code (entry.entry != NULL && entry.length > 0) \endcode
  1770.  *    \code memchr(entry.entry, '=', entry.length) != NULL \endcode
  1771.  *    \code field_name != NULL \endcode
  1772.  *    \code field_value != NULL \endcode
  1773.  * \retval FLAC__bool
  1774.  *    \c false if memory allocation fails or \a entry does not comply with the
  1775.  *    Vorbis comment specification, else \c true.
  1776.  */
  1777. FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_to_name_value_pair(const FLAC__StreamMetadata_VorbisComment_Entry entry, char **field_name, char **field_value);
  1778.  
  1779. /** Check if the given Vorbis comment entry's field name matches the given
  1780.  *  field name.
  1781.  *
  1782.  * \param entry              An existing Vorbis comment entry.
  1783.  * \param field_name         The field name to check.
  1784.  * \param field_name_length  The length of \a field_name, not including the
  1785.  *                           terminating \c NUL.
  1786.  * \assert
  1787.  *    \code (entry.entry != NULL && entry.length > 0) \endcode
  1788.  * \retval FLAC__bool
  1789.  *    \c true if the field names match, else \c false
  1790.  */
  1791. FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length);
  1792.  
  1793. /** Find a Vorbis comment with the given field name.
  1794.  *
  1795.  *  The search begins at entry number \a offset; use an offset of 0 to
  1796.  *  search from the beginning of the comment array.
  1797.  *
  1798.  * \param object      A pointer to an existing VORBIS_COMMENT object.
  1799.  * \param offset      The offset into the comment array from where to start
  1800.  *                    the search.
  1801.  * \param field_name  The field name of the comment to find.
  1802.  * \assert
  1803.  *    \code object != NULL \endcode
  1804.  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1805.  *    \code field_name != NULL \endcode
  1806.  * \retval int
  1807.  *    The offset in the comment array of the first comment whose field
  1808.  *    name matches \a field_name, or \c -1 if no match was found.
  1809.  */
  1810. FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name);
  1811.  
  1812. /** Remove first Vorbis comment matching the given field name.
  1813.  *
  1814.  * \param object      A pointer to an existing VORBIS_COMMENT object.
  1815.  * \param field_name  The field name of comment to delete.
  1816.  * \assert
  1817.  *    \code object != NULL \endcode
  1818.  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1819.  * \retval int
  1820.  *    \c -1 for memory allocation error, \c 0 for no matching entries,
  1821.  *    \c 1 for one matching entry deleted.
  1822.  */
  1823. FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name);
  1824.  
  1825. /** Remove all Vorbis comments matching the given field name.
  1826.  *
  1827.  * \param object      A pointer to an existing VORBIS_COMMENT object.
  1828.  * \param field_name  The field name of comments to delete.
  1829.  * \assert
  1830.  *    \code object != NULL \endcode
  1831.  *    \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
  1832.  * \retval int
  1833.  *    \c -1 for memory allocation error, \c 0 for no matching entries,
  1834.  *    else the number of matching entries deleted.
  1835.  */
  1836. FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name);
  1837.  
  1838. /** Create a new CUESHEET track instance.
  1839.  *
  1840.  *  The object will be "empty"; i.e. values and data pointers will be \c 0.
  1841.  *
  1842.  * \retval FLAC__StreamMetadata_CueSheet_Track*
  1843.  *    \c NULL if there was an error allocating memory, else the new instance.
  1844.  */
  1845. FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(void);
  1846.  
  1847. /** Create a copy of an existing CUESHEET track object.
  1848.  *
  1849.  *  The copy is a "deep" copy, i.e. dynamically allocated data within the
  1850.  *  object is also copied.  The caller takes ownership of the new object and
  1851.  *  is responsible for freeing it with
  1852.  *  FLAC__metadata_object_cuesheet_track_delete().
  1853.  *
  1854.  * \param object  Pointer to object to copy.
  1855.  * \assert
  1856.  *    \code object != NULL \endcode
  1857.  * \retval FLAC__StreamMetadata_CueSheet_Track*
  1858.  *    \c NULL if there was an error allocating memory, else the new instance.
  1859.  */
  1860. FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object);
  1861.  
  1862. /** Delete a CUESHEET track object
  1863.  *
  1864.  * \param object       A pointer to an existing CUESHEET track object.
  1865.  * \assert
  1866.  *    \code object != NULL \endcode
  1867.  */
  1868. FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object);
  1869.  
  1870. /** Resize a track's index point array.
  1871.  *
  1872.  *  If the size shrinks, elements will truncated; if it grows, new blank
  1873.  *  indices will be added to the end.
  1874.  *
  1875.  * \param object           A pointer to an existing CUESHEET object.
  1876.  * \param track_num        The index of the track to modify.  NOTE: this is not
  1877.  *                         necessarily the same as the track's \a number field.
  1878.  * \param new_num_indices  The desired length of the array; may be \c 0.
  1879.  * \assert
  1880.  *    \code object != NULL \endcode
  1881.  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1882.  *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  1883.  *    \code (object->data.cue_sheet.tracks[track_num].indices == NULL && object->data.cue_sheet.tracks[track_num].num_indices == 0) ||
  1884.  * (object->data.cue_sheet.tracks[track_num].indices != NULL && object->data.cue_sheet.tracks[track_num].num_indices > 0) \endcode
  1885.  * \retval FLAC__bool
  1886.  *    \c false if memory allocation error, else \c true.
  1887.  */
  1888. FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices);
  1889.  
  1890. /** Insert an index point in a CUESHEET track at the given index.
  1891.  *
  1892.  * \param object       A pointer to an existing CUESHEET object.
  1893.  * \param track_num    The index of the track to modify.  NOTE: this is not
  1894.  *                     necessarily the same as the track's \a number field.
  1895.  * \param index_num    The index into the track's index array at which to
  1896.  *                     insert the index point.  NOTE: this is not necessarily
  1897.  *                     the same as the index point's \a number field.  The
  1898.  *                     indices at and after \a index_num move right one
  1899.  *                     position.  To append an index point to the end, set
  1900.  *                     \a index_num to
  1901.  *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
  1902.  * \param index        The index point to insert.
  1903.  * \assert
  1904.  *    \code object != NULL \endcode
  1905.  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1906.  *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  1907.  *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
  1908.  * \retval FLAC__bool
  1909.  *    \c false if realloc() fails, else \c true.
  1910.  */
  1911. FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num, FLAC__StreamMetadata_CueSheet_Index index);
  1912.  
  1913. /** Insert a blank index point in a CUESHEET track at the given index.
  1914.  *
  1915.  *  A blank index point is one in which all field values are zero.
  1916.  *
  1917.  * \param object       A pointer to an existing CUESHEET object.
  1918.  * \param track_num    The index of the track to modify.  NOTE: this is not
  1919.  *                     necessarily the same as the track's \a number field.
  1920.  * \param index_num    The index into the track's index array at which to
  1921.  *                     insert the index point.  NOTE: this is not necessarily
  1922.  *                     the same as the index point's \a number field.  The
  1923.  *                     indices at and after \a index_num move right one
  1924.  *                     position.  To append an index point to the end, set
  1925.  *                     \a index_num to
  1926.  *                     \c object->data.cue_sheet.tracks[track_num].num_indices .
  1927.  * \assert
  1928.  *    \code object != NULL \endcode
  1929.  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1930.  *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  1931.  *    \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
  1932.  * \retval FLAC__bool
  1933.  *    \c false if realloc() fails, else \c true.
  1934.  */
  1935. FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
  1936.  
  1937. /** Delete an index point in a CUESHEET track at the given index.
  1938.  *
  1939.  * \param object       A pointer to an existing CUESHEET object.
  1940.  * \param track_num    The index into the track array of the track to
  1941.  *                     modify.  NOTE: this is not necessarily the same
  1942.  *                     as the track's \a number field.
  1943.  * \param index_num    The index into the track's index array of the index
  1944.  *                     to delete.  NOTE: this is not necessarily the same
  1945.  *                     as the index's \a number field.
  1946.  * \assert
  1947.  *    \code object != NULL \endcode
  1948.  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1949.  *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  1950.  *    \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode
  1951.  * \retval FLAC__bool
  1952.  *    \c false if realloc() fails, else \c true.
  1953.  */
  1954. FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
  1955.  
  1956. /** Resize the track array.
  1957.  *
  1958.  *  If the size shrinks, elements will truncated; if it grows, new blank
  1959.  *  tracks will be added to the end.
  1960.  *
  1961.  * \param object            A pointer to an existing CUESHEET object.
  1962.  * \param new_num_tracks    The desired length of the array; may be \c 0.
  1963.  * \assert
  1964.  *    \code object != NULL \endcode
  1965.  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1966.  *    \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) ||
  1967.  * (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode
  1968.  * \retval FLAC__bool
  1969.  *    \c false if memory allocation error, else \c true.
  1970.  */
  1971. FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks);
  1972.  
  1973. /** Sets a track in a CUESHEET block.
  1974.  *
  1975.  *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
  1976.  *  takes ownership of the \a track pointer.
  1977.  *
  1978.  * \param object       A pointer to an existing CUESHEET object.
  1979.  * \param track_num    Index into track array to set.  NOTE: this is not
  1980.  *                     necessarily the same as the track's \a number field.
  1981.  * \param track        The track to set the track to.  You may safely pass in
  1982.  *                     a const pointer if \a copy is \c true.
  1983.  * \param copy         See above.
  1984.  * \assert
  1985.  *    \code object != NULL \endcode
  1986.  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  1987.  *    \code track_num < object->data.cue_sheet.num_tracks \endcode
  1988.  *    \code (track->indices != NULL && track->num_indices > 0) ||
  1989.  * (track->indices == NULL && track->num_indices == 0)
  1990.  * \retval FLAC__bool
  1991.  *    \c false if \a copy is \c true and malloc() fails, else \c true.
  1992.  */
  1993. FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
  1994.  
  1995. /** Insert a track in a CUESHEET block at the given index.
  1996.  *
  1997.  *  If \a copy is \c true, a copy of the track is stored; otherwise, the object
  1998.  *  takes ownership of the \a track pointer.
  1999.  *
  2000.  * \param object       A pointer to an existing CUESHEET object.
  2001.  * \param track_num    The index at which to insert the track.  NOTE: this
  2002.  *                     is not necessarily the same as the track's \a number
  2003.  *                     field.  The tracks at and after \a track_num move right
  2004.  *                     one position.  To append a track to the end, set
  2005.  *                     \a track_num to \c object->data.cue_sheet.num_tracks .
  2006.  * \param track        The track to insert.  You may safely pass in a const
  2007.  *                     pointer if \a copy is \c true.
  2008.  * \param copy         See above.
  2009.  * \assert
  2010.  *    \code object != NULL \endcode
  2011.  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  2012.  *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
  2013.  * \retval FLAC__bool
  2014.  *    \c false if \a copy is \c true and malloc() fails, else \c true.
  2015.  */
  2016. FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
  2017.  
  2018. /** Insert a blank track in a CUESHEET block at the given index.
  2019.  *
  2020.  *  A blank track is one in which all field values are zero.
  2021.  *
  2022.  * \param object       A pointer to an existing CUESHEET object.
  2023.  * \param track_num    The index at which to insert the track.  NOTE: this
  2024.  *                     is not necessarily the same as the track's \a number
  2025.  *                     field.  The tracks at and after \a track_num move right
  2026.  *                     one position.  To append a track to the end, set
  2027.  *                     \a track_num to \c object->data.cue_sheet.num_tracks .
  2028.  * \assert
  2029.  *    \code object != NULL \endcode
  2030.  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  2031.  *    \code object->data.cue_sheet.num_tracks >= track_num \endcode
  2032.  * \retval FLAC__bool
  2033.  *    \c false if \a copy is \c true and malloc() fails, else \c true.
  2034.  */
  2035. FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num);
  2036.  
  2037. /** Delete a track in a CUESHEET block at the given index.
  2038.  *
  2039.  * \param object       A pointer to an existing CUESHEET object.
  2040.  * \param track_num    The index into the track array of the track to
  2041.  *                     delete.  NOTE: this is not necessarily the same
  2042.  *                     as the track's \a number field.
  2043.  * \assert
  2044.  *    \code object != NULL \endcode
  2045.  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  2046.  *    \code object->data.cue_sheet.num_tracks > track_num \endcode
  2047.  * \retval FLAC__bool
  2048.  *    \c false if realloc() fails, else \c true.
  2049.  */
  2050. FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num);
  2051.  
  2052. /** Check a cue sheet to see if it conforms to the FLAC specification.
  2053.  *  See the format specification for limits on the contents of the
  2054.  *  cue sheet.
  2055.  *
  2056.  * \param object     A pointer to an existing CUESHEET object.
  2057.  * \param check_cd_da_subset  If \c true, check CUESHEET against more
  2058.  *                   stringent requirements for a CD-DA (audio) disc.
  2059.  * \param violation  Address of a pointer to a string.  If there is a
  2060.  *                   violation, a pointer to a string explanation of the
  2061.  *                   violation will be returned here. \a violation may be
  2062.  *                   \c NULL if you don't need the returned string.  Do not
  2063.  *                   free the returned string; it will always point to static
  2064.  *                   data.
  2065.  * \assert
  2066.  *    \code object != NULL \endcode
  2067.  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  2068.  * \retval FLAC__bool
  2069.  *    \c false if cue sheet is illegal, else \c true.
  2070.  */
  2071. FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation);
  2072.  
  2073. /** Calculate and return the CDDB/freedb ID for a cue sheet.  The function
  2074.  *  assumes the cue sheet corresponds to a CD; the result is undefined
  2075.  *  if the cuesheet's is_cd bit is not set.
  2076.  *
  2077.  * \param object     A pointer to an existing CUESHEET object.
  2078.  * \assert
  2079.  *    \code object != NULL \endcode
  2080.  *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
  2081.  * \retval FLAC__uint32
  2082.  *    The unsigned integer representation of the CDDB/freedb ID
  2083.  */
  2084. FLAC_API FLAC__uint32 FLAC__metadata_object_cuesheet_calculate_cddb_id(const FLAC__StreamMetadata *object);
  2085.  
  2086. /** Sets the MIME type of a PICTURE block.
  2087.  *
  2088.  *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
  2089.  *  takes ownership of the pointer.  The existing string will be freed if this
  2090.  *  function is successful, otherwise the original string will remain if \a copy
  2091.  *  is \c true and malloc() fails.
  2092.  *
  2093.  * \note It is safe to pass a const pointer to \a mime_type if \a copy is \c true.
  2094.  *
  2095.  * \param object      A pointer to an existing PICTURE object.
  2096.  * \param mime_type   A pointer to the MIME type string.  The string must be
  2097.  *                    ASCII characters 0x20-0x7e, NUL-terminated.  No validation
  2098.  *                    is done.
  2099.  * \param copy        See above.
  2100.  * \assert
  2101.  *    \code object != NULL \endcode
  2102.  *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  2103.  *    \code (mime_type != NULL) \endcode
  2104.  * \retval FLAC__bool
  2105.  *    \c false if \a copy is \c true and malloc() fails, else \c true.
  2106.  */
  2107. FLAC_API FLAC__bool FLAC__metadata_object_picture_set_mime_type(FLAC__StreamMetadata *object, char *mime_type, FLAC__bool copy);
  2108.  
  2109. /** Sets the description of a PICTURE block.
  2110.  *
  2111.  *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
  2112.  *  takes ownership of the pointer.  The existing string will be freed if this
  2113.  *  function is successful, otherwise the original string will remain if \a copy
  2114.  *  is \c true and malloc() fails.
  2115.  *
  2116.  * \note It is safe to pass a const pointer to \a description if \a copy is \c true.
  2117.  *
  2118.  * \param object      A pointer to an existing PICTURE object.
  2119.  * \param description A pointer to the description string.  The string must be
  2120.  *                    valid UTF-8, NUL-terminated.  No validation is done.
  2121.  * \param copy        See above.
  2122.  * \assert
  2123.  *    \code object != NULL \endcode
  2124.  *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  2125.  *    \code (description != NULL) \endcode
  2126.  * \retval FLAC__bool
  2127.  *    \c false if \a copy is \c true and malloc() fails, else \c true.
  2128.  */
  2129. FLAC_API FLAC__bool FLAC__metadata_object_picture_set_description(FLAC__StreamMetadata *object, FLAC__byte *description, FLAC__bool copy);
  2130.  
  2131. /** Sets the picture data of a PICTURE block.
  2132.  *
  2133.  *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
  2134.  *  takes ownership of the pointer.  Also sets the \a data_length field of the
  2135.  *  metadata object to what is passed in as the \a length parameter.  The
  2136.  *  existing data will be freed if this function is successful, otherwise the
  2137.  *  original data and data_length will remain if \a copy is \c true and
  2138.  *  malloc() fails.
  2139.  *
  2140.  * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
  2141.  *
  2142.  * \param object  A pointer to an existing PICTURE object.
  2143.  * \param data    A pointer to the data to set.
  2144.  * \param length  The length of \a data in bytes.
  2145.  * \param copy    See above.
  2146.  * \assert
  2147.  *    \code object != NULL \endcode
  2148.  *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  2149.  *    \code (data != NULL && length > 0) ||
  2150.  * (data == NULL && length == 0 && copy == false) \endcode
  2151.  * \retval FLAC__bool
  2152.  *    \c false if \a copy is \c true and malloc() fails, else \c true.
  2153.  */
  2154. FLAC_API FLAC__bool FLAC__metadata_object_picture_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, FLAC__uint32 length, FLAC__bool copy);
  2155.  
  2156. /** Check a PICTURE block to see if it conforms to the FLAC specification.
  2157.  *  See the format specification for limits on the contents of the
  2158.  *  PICTURE block.
  2159.  *
  2160.  * \param object     A pointer to existing PICTURE block to be checked.
  2161.  * \param violation  Address of a pointer to a string.  If there is a
  2162.  *                   violation, a pointer to a string explanation of the
  2163.  *                   violation will be returned here. \a violation may be
  2164.  *                   \c NULL if you don't need the returned string.  Do not
  2165.  *                   free the returned string; it will always point to static
  2166.  *                   data.
  2167.  * \assert
  2168.  *    \code object != NULL \endcode
  2169.  *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
  2170.  * \retval FLAC__bool
  2171.  *    \c false if PICTURE block is illegal, else \c true.
  2172.  */
  2173. FLAC_API FLAC__bool FLAC__metadata_object_picture_is_legal(const FLAC__StreamMetadata *object, const char **violation);
  2174.  
  2175. /* \} */
  2176.  
  2177. #ifdef __cplusplus
  2178. }
  2179. #endif
  2180.  
  2181. #endif
  2182.